The only change in the Appearance 1.0.4 SDK from the Appearance 1.0.3 SDK is the updated .Keyboard font 3.1 that shipped with Mac OS 8.6. All other information in the SDK is the same. The 3.1 version of the .Keyboard font contains fifteen additional glyphs for displaying the function keys F1 to F15 in menus and dialogs.
Version Information
See the enclosed document "tb39.html" for details on the history of Appearance and the Appearance SDK.
Installation Instructions
Important: You should only install components from this SDK into a System Folder whose version is 8.1 or earlier. Do not install components from this SDK into a System Folder whose version is 8.5 or later, as the functionality is already included in the System file in those releases.
Install "Appearance Extension" into the Extensions folder. Install the ".Keyboard" font suitcase into the Fonts folder. Install one of the Appearance control panels into the Control Panels folder.
There are two variants of the Appearance control panel in the SDK.
The first control panel, "Appearance", has the file type 'APPC', so Finder in Mac OS 8 or later will automagically route it into the Control Panels folder when it is dropped onto the (closed) System Folder icon. You should not install this version of the control panel onto systems earlier than 8.0.
The other control panel, "AppearanceCDEV", is really an application, and will not automagically route to the Control Panels folder under any version of Mac OS. You should install this version of the control panel into the Control Panels folder on Systems earlier than 8.0 and name it "Appearance" (for English locales).
If you plan to bundle Appearance 1.0.X with your software and install it on System 7.x systems, please also install the preferences from the folder "Prefs for use with System 7.x" into the Preferences folder, so that the user will get the platinum appearance and sticky menu behavior for your Appearance-savvy application, but the rest of their system will continue to look and behave as it did before installation.
If you install Appearance 1.0.X on a System 7.x machine, you should disable (by moving into the disabled folder) the "Color" and "WindowShade" control panels, since the "Appearance" control panel supercedes these. WindowShade is incompatible with the Appearance extension, and interferes with the ability to double-click in the title bar as a way to collapse or expand a window.
You should not install anything which is not included in this SDK, including any version of the "Date & Time" control panel. (A version of this control panel was included in early seeds of the SDK, but we were able to remove the need for it before the SDK shipped.)
When installing a later version of Appearance over an older one, only the extension and control panel should be replaced; the preferences should be left alone.
Under Mac OS 8 or later, the extension must be called "Appearance Extension" and cannot be renamed. Otherwise, if the user were to shift-boot, the extension would not load, and the Finder could not start, since it requires Appearance, and booting would fail.
Appearance 1.0.X runs on 68K and PowerPC processors; it supports three run-time models: Classic 68K, CFM-68K, and PowerPC CFM. Color QuickDraw is required for Appearance, so it implicitly requires a 68020 or better processor.
Because of the complexity of installation, we recommend developers provide an installer and avoid asking the user to perform the installation.
Known Issues
1. The 'alrx' resources in version 1.0 (of the API) did not work as advertised. Do not use 'alrx' resources when only version 1.0 is present. If you wish to use 'alrx' resources, you must require Appearance 1.0.2 or later. Use only the format as described in the Rez template supplied in this SDK (or in a version of Universal Headers later than the headers in this SDK).
2. As of API version 1.0.1, the list box control turns off drawing on the list it creates. This was done to fix some rather nasty behavioral problems it had. Please be aware of this, as it means that if you manipulate the list directly, you will need to call LSetDrawingMode( true... ) before you draw. You should restore it to false when done.
3. The included d e v e l o p article mentions "wide" hierarchical IDs, i.e. the ability to use IDs for hierarchical menus that are in the full short integer range, as opposed to the byte range (1-255). This functionality did not make it into Appearance 1.0.X. Regardless, please make use of SetMenuItemHierarchicalID and use 'xmnu' resources to specify hierarchical IDs. Doing so will prepare your code for Mac OS 8.5, in which wide ID support is available.
4. If you are using the new Menu Manager routines provided by Appearance to draw Appearance-savvy menus, there is some late breaking news you need to be aware of to make this work in the future. To do this correctly, you must respond to a new menu definition function (MDEF) message kMenuThemeSavvyMsg (aka mIsThemeSavvy == 7). Menu Manager will send this message to your MDEF to determine whether a theme-savvy background should be drawn for your menu. To respond properly, return kThemeSavvyMenuResponse (== 0x7473) in the whichItem parameter to indicate you want a theme-savvy background. Any other response (or lack thereof), will result in a System 7-style background being drawn. This will most likely sharply contrast with the rest of the current theme, so we urge you to respond to this message. This message is not implemented by Appearance 1.0.X, but is implemented in the Menu Manager in Mac OS 8.5.
Known Bugs
A: Characters in the menu bar when running Painter 5 can be lost (certain characters aren't drawn) when ATM is installed and the Charcoal font is the current system font. Switching to the Chicago font seems to alleviate the problem.
B: MenuEvent doesn't work with Dvorak keyboards that have QWERTY command key mappings.
C: Passing a non-existent menu ID to a group box with a popup title will crash.
D: Passing 254 to HiliteControl for a group box control will not redraw the control. If you use HiliteControl to disable controls, you should always pass 255 for group boxes.
E: The radio group control is documented to work correctly with bevel buttons with sticky behavior, but in fact this feature is broken. Radio groups with radio buttons do work correctly.
F: CountSubControls returns the wrong number of sub-controls for list boxes.
G: Timbuktu will not connect when a version of the Appearance Extension prior to 1.0.3 is installed. Farallon has been notified of the problem and we have given them a solution. The fix will be in a release of Timbuktu following 4.0. The problem is related to the keyboard font being present in the extension, as opposed to in a suitcase, which it is as of version 1.0.3.
H: Setting tab information (via SetControlData) doesn't always work. DTS has work-around code for some of the problems. When requesting a work-around, make sure to specify the symptoms of the problem you are experiencing, so DTS can provide the correct work-around, if any is available, and you can avoid expending a support incident unnecessarily.
Contact Information
Please email suggestions for improvements to the Toolbox or the Appearance SDK to <toolbox@apple.com>. Please report bugs via <http://developer.apple.com/bugreporter/>.
